/*
 * Copyright 2000-2011 Worth Enterprises, Inc. All rights reserved.
 */
package com.worthent.foundation.util.state;

/**
 * Specifies the methods implemented by objects that represent an instance of
 * the state table. Implementations must be able to acquire the state table
 * metadata ({@link StateTableDef}) and acquire the current and prior state of
 * the state table and update the new current and prior states based on
 * information in the {@link StateEvent}. Implementations may retrieve and store
 * state information using some persistent store such as a database or keep the
 * information in memory depending on the life span of the state table.
 * Implementations may also provide additional functionality to retrieve and
 * update the object or objects acted upon by the state table.
 * 
 * @author Erik K. Worth
 * @version $Id: StateTable.java 2 2011-11-28 00:10:06Z erik.k.worth@gmail.com $
 */
public interface StateTable {
    /** Returns the name of the state table */
    String getStateTableName();

    /**
     * Returns the object that responds to each state transition or
     * <code>null</code> if none was registered.
     */
    StateTransitioner getTransitioner();

    /**
     * Returns the registered handler that responds to state transition errors
     * or <code>null</code> if none is registered.
     * 
     * @return the registered handler that responds to state transition errors
     *         or <code>null</code> if none is registered
     */
    StateErrorHandler getErrorHandler();

    /** Returns the state table metadata */
    StateTableDef getStateTableDefinition(StateEvent event)
        throws StateExeException;

    /**
     * Sets the current state in the state table data object to the initial
     * state of the state table. This is typically called from the
     * implementation of the {@link StateTableController#start()} method.
     * 
     * @throws StateDefException thrown when there is an error initializing the
     *             state table
     */
    void initializeStateTableData() throws StateDefException;

    /**
     * Returns a copy of the state table data object that minimally holds the
     * current and prior states of the state table instance. This method is
     * called by the engine when the event processing begins for the specified
     * event. This method returns a copy that is then modified by the state
     * transition actors. If the processing completes successfully, the engine
     * sets the updated copy back into this state table via a call to
     * {@link #setStateTableData(StateEvent, StateTableData)}.
     * 
     * @param event the event being processed
     * 
     * @throws StateExeException thrown when there is an error retrieving the
     *             state history
     */
    StateTableData getStateTableData(StateEvent event)
        throws StateExeException;

    /**
     * Updates the state table instance with a new value of the data object that
     * minimally holds the current and prior states of the state table instance.
     * This method is called by the engine when the processing has completed
     * successfully for the event. The data object passed in here is the updated
     * copy modified by the state transition actors.
     * 
     * @param event the event that triggered the state table to update its data
     * @param dataObject the new data object to set into the state table
     *            instance
     * 
     * @throws StateExeException thrown when there is an error setting the state
     *             history
     */
    void setStateTableData(StateEvent event, StateTableData dataObject)
        throws StateExeException;

}
